The Companion Button Controller (attached to Gameboard) exposes all the companion button features available to creators.

Video Walkthrough:

The Gameboard prefab is always available in your game as long as the SDK has been integrated. In order to access it from our custom Mono Behavior we just need to find it by its tag.

    GameObject gameboardObject = GameObject.FindWithTag("Gameboard");

With access to our Gameboard object we can then move on to obtain a reference to the Companion Buttons Controller. This is the controller that handles all the functions related to companion buttons.

NOTE: Right now, some of the button actions are tied to Cards. For example, buttons set with SetCompanionButtonValues will be tied to the CardController's CardButtonPressed event. Buttons set in the Dialog are tied to the CompanionButtonPressed event. There are plans to refactor this in future versions.

We will first need to define a reference to the controller to make it available throughout our script:

     CompanionButtonController companionButtonController;
     CardController cardController;

With our reference defined, we can now proceed to listen for button events. In our case well have a function called OnStandardButtonPressed handle this events.

     companionButtonController = gameboardObject.GetComponent<CompanionButtonController>();
     cardController = gameboardObject.GetComponent<CardController>();
     companionButtonController.CompanionButtonPressed += OnStandardButtonPressed;
     cardController.CardButtonPressed += OnCardButtonPressed;

Now that we are able to receive the button press events all that remains is to handle them in the game.

    void OnStandardButtonPressed(GameboardCompanionButtonPressedEventArgs companionButtonEvent)
    {
        // Handle pressed event of the Standard button on Companion. (Dialog buttons)
    }

    void OnCardButtonPressed(GameboardCompanionCardsButtonPressedEventArgs companionButtonEvent)
    {
       // Handle pressed event of card button (Includes cardId in the event args)
    }

With the controller at hand we can also send requests to Companion to display a given button.

NOTE: Currently adding buttons in this way is only supported in the Cards view. Pressing these buttons will send a CardButtonPressed event that can be listened to from the CardController.

By default, the button is not visible on the companion app, it must be enabled with SetCompanionButtonVisiblity

Button placement

There are currently 3 preset buttonIds = "1", "2", and "3" "1" will appear in the bottom center of the screen "2" will appear on the bottom left of the screen "3" will appear on the bottom right of the screen

If any of the preset ids are set, they will override other buttons.

If we set buttons with the ids { "testing0", "testing1", "testing2", "3", "1", "2", "testing3", "testing4", "testing5" } only "3", "1", "2" will be displayed with "1" in the center, "2" on the left, and "3" on the right.

If we set buttons with the ids { "testing0", "testing1", "testing2" } we will 3 see buttons with testing0 in the center, testing1 on the left, and testing2 on the right.

If we set buttons with the ids { "2", "3" } we will see 2 buttons with "2" on the left, and "3" on the right.

The buttonId can be set to something other than 1, 2, and 3, but if 1, 2, or 3 are present they will override other buttons previously set.

Example

In this example we are creating a button that you want to appear in the middle position (id "1") on "userABC"'s companion with the text "Hello World", the specified callback identifier of "HelloWorldCallback", and an optional texture defined by ID "textureId".

    // Note: These assets need to be uploaded using the Asset Controller before making this call or the button textures won't show.
    await companionButtonController.SetCompanionButtonValues("userABC", "1", "Hello World.", "HelloWorldCallback", "textureId");
    //Set that button visible
    await companionButtonController.SetCompanionButtonVisiblity("userABC", "1", true);

With SDK version 2.0.0+, you can create buttons without the id being coupled to the button position.

NOTE: Currently adding buttons in this way is only supported in the Cards view. Pressing these buttons will send a CardButtonPressed event that can be listened to from the CardController.

By default, the button is not visible on the companion app, it must be enabled with SetCompanionButtonVisiblity

Example

In this example we are creating a button that you want to appear in the middle position on "userABC"'s companion with the text "Hello World", the specified callback identifier of "HelloWorldCallback", and an optional texture defined by ID "textureId".

    // Note: These assets need to be uploaded using the Asset Controller before making this call or the button textures won't show.
    await companionButtonController.SetCompanionCardButton("userABC", "buttonId", "Hello World.", "HelloWorldCallback", "textureId", CardButtonPosition.Center);
    //Set that button visible
    await companionButtonController.SetCompanionButtonVisiblity("userABC", "buttonId", true);

Setting multiple buttons

With SDK version 2.0.0+, we also added a method that allows setting and showing multiple buttons at once. You will get back an array of responses, corresponding to the response received when setting/showing each button.

CompanionMessageResponseArgs[] responses = await companionButtonController.SetAndShowMultipleCompanionCardButtons("userABC",
            new CompanionCardButton[]
                {
                    new CompanionCardButton("LeftBtnId", "LeftBtn", CardButtonPosition.Left),
                    new CompanionCardButton("CenterBtnId", "CenterBtn", CardButtonPosition.Center),
                    new CompanionCardButton("RightBtnId", "RightBtn", CardButtonPosition.Right) {
                        //Optional params
                        assetId = "textureId",
                        buttonCallback = "RightCallback",
                    },
                }
            );

Although we are working in a managed environment it is always a good idea to clean the listeners when no longer needed.

    void OnDestroy()
    {
        companionButtonController.CompanionButtonPressed -= OnStandardButtonPressed;
        cardController.CardButtonPressed -= OnCardButtonPressed;
    }

This section include the entire code in one single, easy to copy section.

    CompanionButtonController companionButtonController;
    CardController cardController;

    // Start is called before the first frame update
    void Start()
    {
        GameObject gameboardObject = GameObject.FindWithTag("Gameboard");
        companionButtonController = gameboardObject.GetComponent<CompanionButtonController>();
        cardController = gameboardObject.GetComponent<CardController>();

        companionButtonController.CompanionButtonPressed += OnStandardButtonPressed;
        cardController.CardButtonPressed += OnCardButtonPressed;
    }

    void OnStandardButtonPressed(GameboardCompanionButtonPressedEventArgs companionButtonEvent)
    {
        // Handle pressed event of the Standard button on Companion.
    }

    void OnCardButtonPressed(GameboardCompanionCardsButtonPressedEventArgs companionButtonEvent)
    {
       // Handle pressed event of card button (Includes cardId in the event args)
    }

    void OnDestroy()
    {
        companionButtonController.CompanionButtonPressed -= OnStandardButtonPressed;
        cardController.CardButtonPressed -= OnCardButtonPressed;
    }